home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 6: Level 6 / 17 Bit - Level 6 (1998)(Epic Marketing)[!].iso / quartz / q0039.dms / q0039.adf / bin / make.doc < prev    next >
Text File  |  1990-12-04  |  11KB  |  310 lines
  1.  
  2.   (c) 1990 S.Hawtin.
  3.   Permission is granted to copy this file and make provided that:
  4.    1) Neither are used for commercial gain
  5.    2) This notice is included in all copies
  6.    3) Altered copies are marked as such.
  7.    4) Each copy of make is accompanied by a copy of this file.
  8.  
  9.   No liability is accepted for the contents of the file.
  10.  
  11.   make.doc        within        make
  12.  
  13. MAKE
  14.     make [-fmakefile][-?][target]
  15.  
  16.   Maintain an up-to-date version of a program.  The options have the 
  17. following meanings
  18.  
  19. -f<makefile>
  20.  
  21.    Take the description from the file <makefile> rather than "Makefile".
  22.  
  23. -?
  24.  
  25.   Print out the commands that would be executed but do not perform them.
  26.  
  27. target
  28.  
  29.   Construct the file <target> rather than the first item in the makefile.  
  30. The special target "$*.blink" will cause the program to create a file 
  31. that can be used by the "Blink" program to link the object files together.
  32.  
  33.   The make command keeps programs up to date, it does this by reading a 
  34. file that describes how to construct a target program and executing all 
  35. the commands required to update the program.
  36.  
  37.   When using 'C' and other compiled languages it is normal to divide the 
  38. source code for a program into many files, this allows you to split the 
  39. code into logical chunks.  Most compiled languages allow you to recompile 
  40. each source file independently to produce an "object" file, the user then 
  41. combines all the object files to produce the actual program with a 
  42. "linker".  Whenever you alter a source file it must be recompiled and the 
  43. resulting "object" file must be relinked into the executable program, it 
  44. can be difficult to remember which files you have changed since the last 
  45. build and what set of tools need to be run on which programs.  The "make" 
  46. program works out which commands need to be executed to bring a program up 
  47. to date and executes them.
  48.  
  49.   An example will explain what the program does, assume you have a program 
  50. called "jim" that combines three source files, "foo.c", "bar.c" and 
  51. "baz.asm".  To use "make" in its simplest form you should create a file 
  52. called "Makefile" containing the lines
  53.  
  54.     jim : foo.o bar.o baz.o
  55.             blink with $*.blink
  56.  
  57. this tells the "make" program that "jim" depends on the object files 
  58. "foo.o", "bar.o" and "baz.o", and that "jim" can be created by the CLI 
  59. command "blink with jim.blink".  You must now construct the file 
  60. "jim.blink" that the "blink" command requires, this is done by the CLI 
  61. command
  62.  
  63.     make $*.blink
  64.  
  65. the "$*" construct will be explained later.
  66.  
  67.   Once the "Makefile" and "jim.blink" files have been created you can use 
  68. the "make" program to construct "jim", just type the command
  69.  
  70.     make
  71.  
  72. and it will call all the commands to make "jim".  Now if you change the 
  73. file "foo.c" and then type the "make" command it will only issue the 
  74. commands required to bring the program up to date, the program will not 
  75. bother to recompile "bar.c" or "baz.asm".  The "make" program is clever 
  76. enough to know that "bar.c" needs to be compiled and "baz.asm" needs to 
  77. be assembled program.
  78.  
  79.   So every time you change a set of the source files you just type "make" 
  80. and all the necessary compilations will be done.  This is well and good, 
  81. assuming we are only going to edit the ".c" and ".asm" files.  If however 
  82. if you change an include file you want "make" to recompile all the 'C' 
  83. source files that include it.  We get make to do this by adding some extra 
  84. lines into the "Makefile".  If the new "Makefile" contains
  85.  
  86.     jim : foo.o bar.o baz.o
  87.             blink with $*.blink
  88.  
  89.     foo.o: fubar.h foo.h
  90.  
  91.     bar.o : fubar.h
  92.  
  93. then every time "fubar.h" is altered "make" will recompile both "foo.c" 
  94. and "bar.c".  Notice that the three items "jim", "foo.o" and "bar.o" must 
  95. be separated by blank lines.  If we now change the file "fubar.h" then the 
  96. "make" command will recompile both "foo.c" and "bar.c".
  97.  
  98.   By default the "make" program always tries to construct the first item 
  99. in the "Makefile", this is why you must put the line
  100.  
  101.     foo.o: fubar.h
  102.  
  103. after
  104.  
  105.     jim : foo.o bar.o baz.o
  106.  
  107. if it was put in before then the "make" program would just make "foo.o" 
  108. and not "jim".  You can get "make" to construct a particular item by 
  109. telling it which target item you want to update, for example to make 
  110. "bar.o" just type the command
  111.  
  112.     make bar.o
  113.  
  114. we have already seen this being used when we created the "jim.blink" file.
  115.  
  116.   So, to summarise, each item in the "Makefile" starts with a file name, 
  117. then after the ':' a list of items that this item depends on, the 
  118. following lines, up to the first blank line, tell "make" the commands 
  119. required to construct the item.  Each item can appear on the left hand 
  120. side as many times as you want so long as you only specify the commands to 
  121. create it once.
  122.  
  123.   You can of course add comments into the "Makefile", any line that starts 
  124. with a '#' is treated as a comment.
  125.  
  126.   One problem you might come across is having too many dependencies to fit 
  127. on a single line, the '\' character tells "make" that the dependencies are 
  128. continued on the next line, so for example
  129.  
  130.     jim: foo.o \
  131.          bar.o \
  132.          baz.o
  133.             blink with $*.blink
  134.  
  135. is the same as the original entry for "jim".  The '\' character must be 
  136. the last character on the line.
  137.  
  138.   Sometimes you want to "make" an item every time you construct the 
  139. program, for example if you have a file "date.c" that consists of
  140.  
  141.     #include <stdio.h>
  142.  
  143.     print_date()
  144.        {/* Print the date the program was last compiled */
  145.         printf("This version was compiled on %s\n",__DATE__);
  146.         }
  147.  
  148. then even though the actual text of the source file does not change you 
  149. want to recompile it whenever the program is compiled.  You can force 
  150. "make" to always recompile this program by appending the special item 
  151. "always", for example by adding the item
  152.  
  153.     date.o : always
  154.  
  155. to the Makefile.  "always" is considered to be newer than everything 
  156. else.  The "__DATE__" macro is an ANSI C extension that returns a string 
  157. containing the compilation date.
  158.  
  159.   Although the "make" program knows how to convert a ".c" program into a 
  160. ".o" program you can override this by adding an item such as
  161.  
  162.     foo.o: foo.c
  163.             NorthC -I:incl/ foo.c
  164.             A68k foo.s
  165.             Delete foo.s
  166.  
  167. whenever "foo.c" is changed the given commands will be executed to create 
  168. "foo.o" rather than the normal commands.
  169.  
  170.   If you have a preferred way to convert ".c" files into ".o" files you 
  171. could type this in after every ".o" file, however "make" will also allow 
  172. you to define a "default" way to convert between the files, if you add the 
  173. item 
  174.  
  175.     .c.o:
  176.             NorthC -I:incl/ $*.c
  177.             A68K $*.s
  178.             Delete $*.s
  179.  
  180. to the "Makefile" this item tells "make" to construct ".o" files from ".c" 
  181. files by calling the commands 
  182.  
  183.     NorthC -I:incl/ $*.c
  184.     A68K $*.s
  185.     Delete $*.s
  186.  
  187. The sequence "$*" is replaced by the base file name.  The base file name 
  188. consists of the name up to the final '.', so for example the base name of 
  189. "jim.2.c" is "jim.2".
  190.  
  191.   "make" will always add some default items to the end of the "Makefile", 
  192. if they do not clash with existing entries, the current default items are
  193.  
  194.     .c.o:
  195.             NorthC -Ot:$*.s $*.c
  196.             A68K -q -g -O$*.o t:$*.s
  197.             Delete t:$*.s
  198.  
  199.     .s.o:
  200.             A68K $*.s
  201.  
  202.     .asm.o:
  203.             A68K $*.asm
  204.  
  205. this tells the "make" program how to compile 'C' programs and assemble 
  206. ".asm" and ".s" files.
  207.  
  208.   You can use the default mechanism to create files with any extension of 
  209. up to four letters, for example
  210.  
  211.     .uil.uid:
  212.             Delete $*.uid
  213.             Motif:Uil/uil -o $*.uid $*.uil
  214.  
  215. tells "make" that each time it finds a reference to a file such as 
  216. "jim.uid" it should construct the file with the commands
  217.  
  218.     Delete jim.uid
  219.     Motif:Uil/uil -o jim.uid jim.uil
  220.  
  221. whenever the "jim.uil" file is altered.
  222.  
  223.   You can split your "Makefile" into multiple files.  When you want to 
  224. read a file, for example "make.depends", just include the command
  225.  
  226.     $<make.depends>
  227.  
  228. in "Makefile".  Make will read the file "make.depends" at that point.
  229.  
  230.   If you wish to read a file other than "Makefile" when you call "make" 
  231. add the "-f" option, for example to read the dependencies from "jim.make"
  232.  
  233.     make -fjim.make
  234.  
  235. will make the first item in the file "jim.make".
  236.  
  237.   If you want to use the "top" optimiser you should add an item
  238.  
  239.     .c.o:
  240.             NorthC -Ot:$*.s $*.c
  241.             top t:$*.s t:$*.s1
  242.             a68k -g -q -O$*.o t:$*.s
  243.             delete t:$*.s t:$*.s1
  244.  
  245. into your makefiles.
  246.  
  247.  
  248. How Make Works
  249.  
  250.   You don't actually have to read this bit but it might help if you cannot 
  251. get "make" to do something complicated.
  252.  
  253.   The "make" command works by creating a dependency tree, for example the 
  254. sequence
  255.  
  256.     jim: foo.o bar.o baz.o
  257.             blink with $*.blink
  258.  
  259.     foo.o: fubar.h foo.h
  260.  
  261.     bar.o: fubar.h
  262.  
  263. will create a dependency tree
  264.  
  265.                            jim
  266.                           / | \
  267.                          /  |  \
  268.                         /   |   \
  269.                        /    |    \
  270.                   foo.o   bar.o   baz.o
  271.                    |  \   /
  272.                    | fubar.h
  273.                    |
  274.                  foo.h
  275.  
  276. "make" then scans this tree to find items that have no create command 
  277. sequence defined.  Any item that we have not yet been told how to make 
  278. will either be a source file, for example "foo.h" or we will have to find 
  279. out how to make it from the defaults list.  So make will now scan the 
  280. tree, when it comes to "foo.o" it discovers that it has a method for 
  281. creating ".o" files from ".c" files, and a ".c" file exists, so it adds 
  282. the default ".c.o" create method to "foo.o" and adds "foo.c" to its 
  283. dependencies.  When it comes to the file "bar.o" because it cannot find 
  284. "bar.c" it looks further down the list of defaults and finds that a 
  285. "bar.asm" file exists.  Once the tree has been scanned it looks like
  286.  
  287.                            jim
  288.                           / | \
  289.                          /  |  \
  290.                         /   |   \
  291.                        /    |    \
  292.                   foo.o   bar.o   baz.o
  293.                  / |  \   /  \      |
  294.             foo.c  | fubar.h  \   baz.asm
  295.                    |           \
  296.                  foo.h        bar.c
  297.  
  298. "make" then goes over this tree to see if any item is older than one of 
  299. its dependencies, when it finds such an item it adds the commands for 
  300. creating this item to an intermediate file in the "t:" directory.
  301.  
  302.   Once it has gone over the tree it calls the AmigaDOS command "execute" 
  303. to run the created command file, I have to call this function because I 
  304. want "make" to stop as soon as one of the commands fails.  I cannot find 
  305. out how to determine the return code of a called program, if anyone out 
  306. there can tell me how to do this please get in touch.
  307.  
  308.   The last thing the program does is to delete the command file it created 
  309. in the "t:" directory.
  310.